# Claude Code Prompt 体系总览 > **一句话摘要**：Claude Code 的 Prompt 体系是一个模块化数组架构，涵盖 6 大子系统（System/Tool/Agent/Memory/Safety/Caching），通过静态-动态分界和缓存感知设计实现高性能多模式 prompt 组装。 > 基于源代码的深度逆向分析，涵盖 System Prompt、Tool Prompt、Agent Prompt、Memory、Safety、Caching 六大子系统。 > 源码入口：`src/constants/prompts.ts` → `getSystemPrompt()`，优先级组装：`src/utils/systemPrompt.ts` → `buildEffectiveSystemPrompt()` ## 报告导航 | 章节 | 内容 | 关键发现 | 交叉引用 | |------|------|---------|---------| | [[14 - System Prompt 架构]] | System Prompt 的完整结构与组装逻辑 | 20+ section 的模块化数组架构 | [[16 - Prompt Caching 与 Context 管理\|Caching]] [[19 - Prompt 工程技巧与设计模式\|设计模式]] | | [[15 - Agent 与 SubAgent Prompt]] | 6+1 种 Agent 类型的 Prompt 差异 | 工具权限矩阵 + Fork cache 优化 | [[10 - 多 Agent 与协调器\|协调器架构]] [[14 - System Prompt 架构\|优先级系统]] | | [[16 - Prompt Caching 与 Context 管理]] | 三级缓存策略 + Auto-Compact 机制 | 静态/动态分界 + 锁存(Latch)模式 | [[14 - System Prompt 架构\|Section缓存]] [[06 - Query 引擎与对话循环\|Query循环]] | | [[17 - 权限系统与 Safety Prompt]] | 10 层纵深防御安全架构 | AI 分类器 + bypass-immune 检查 | [[05 - 权限系统\|权限基础]] [[14 - System Prompt 架构\|CYBER_RISK]] | | [[18 - Memory 与 Hooks 系统]] | 6 层 Memory + 27 种 Hook 事件 | CLAUDE.md 注入机制 + Hook 双向通信 | [[11 - 配置与内存系统\|配置系统]] [[14 - System Prompt 架构\|User Context]] | | [[19 - Prompt 工程技巧与设计模式]] | 12 个值得学习的 Prompt 设计模式 | Scratchpad CoT + 缓存感知设计 | [[12 - 关键设计模式\|架构模式]] [[14 - System Prompt 架构\|Section设计]] | | [[20 - Tool 系统 Prompt 详解]] | 40 个工具的完整 Prompt 分析 | 工具引导路由网络 + 延迟加载 | [[04 - Tool 系统\|Tool基础]] [[14 - System Prompt 架构\|工具使用指南]] | | [[21 - 用户输入处理与消息格式化]] | 输入到 API 的完整链路 | 5 种消息类型 + Skill 系统 | [[07 - 命令系统\|命令系统]] [[06 - Query 引擎与对话循环\|Query循环]] | ## 核心架构图 ```mermaid-like ┌─────────────────────────────────────────────────────────────┐ │ Claude Code Prompt 体系 │ ├──────────────────┬──────────────────┬───────────────────────┤ │ System Prompt │ Tool Prompts │ Agent Prompts │ │ (string[]) │ (description) │ (per-type system) │ │ │ │ │ │ ┌──────────────┐ │ ┌──────────────┐ │ ┌───────────────────┐ │ │ │ 静态区(7节) │ │ │ Bash │ │ │ general-purpose │ │ │ │ ─ BOUNDARY ─ │ │ │ Read/Write │ │ │ Explore (haiku) │ │ │ │ 动态区(13节) │ │ │ Edit/Glob │ │ │ Plan (只读) │ │ │ └──────────────┘ │ │ Grep/Agent │ │ │ verification (红) │ │ │ │ │ WebFetch/... │ │ │ claude-code-guide │ │ │ │ └──────────────┘ │ │ fork (继承父级) │ │ │ │ │ │ coordinator │ │ │ │ │ └───────────────────┘ │ ├──────────────────┴──────────────────┴───────────────────────┤ │ 支撑子系统 │ │ ┌────────────┐ ┌────────────┐ ┌────────────────────────┐ │ │ │ Memory │ │ Permission │ │ Prompt Caching │ │ │ │ 6层CLAUDE │ │ 10层纵深 │ │ global/org/ephemeral │ │ │ │ .md系统 │ │ 防御 │ │ + Auto-Compact │ │ │ └────────────┘ └────────────┘ └────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ## Prompt 数据流全景 ``` 用户输入 → 消息格式化(21) → Query 引擎(06) ↓ ┌─ buildEffectiveSystemPrompt() ─┐ │ 优先级选择(14§四) │ │ override > coordinator > agent │ │ > custom > default │ └────────────┬───────────────────┘ ↓ ┌─ getSystemPrompt()(14§二) ─────────────┐ │ 静态区(7节) + BOUNDARY + 动态区(13节) │ └────────────┬──────────────────────────┘ ↓ ┌─ getSystemContext()(14§一) ──┐ │ gitStatus + cacheBreaker │ └──────────────┬──────────────┘ ↓ ┌─ getUserContext()(14§一) ────────┐ │ claudeMd + currentDate │ │ (注入为第一条 user message) │ └──────────────┬──────────────────┘ ↓ API 调用 → splitSysPromptPrefix()(16) → 缓存分块 ``` > 括号内数字如 `(14§四)` 表示对应报告章节，可通过 [[14 - System Prompt 架构]] 等链接跳转。 ## 关键数字 | 指标 | 数值 | 相关章节 | |------|------|---------| | System Prompt sections | 20+ 个独立 section | [[14 - System Prompt 架构]] | | 内置工具数量 | 40 个 | [[20 - Tool 系统 Prompt 详解]] | | Agent 类型 | 6 种用户可见 + 1 种内部（statusline-setup）+ 自定义 | [[15 - Agent 与 SubAgent Prompt]] | | Memory 层级 | 6 层（Managed → TeamMem）| [[18 - Memory 与 Hooks 系统]] | | Hook 事件类型 | 27 种 | [[18 - Memory 与 Hooks 系统]] | | 权限防御层次 | 10 层纵深 | [[17 - 权限系统与 Safety Prompt]] | | Cache 作用域 | 3 级（global/org/ephemeral）| [[16 - Prompt Caching 与 Context 管理]] | | Auto-Compact 阈值 | context_window - 33K tokens | [[16 - Prompt Caching 与 Context 管理]] | ## 四种运行模式的 Prompt 差异 Claude Code 的 system prompt 会根据运行模式选择完全不同的 prompt 路径（详见 [[14 - System Prompt 架构#四、System Prompt 优先级系统]]）： | 模式 | 触发条件 | Prompt 特征 | 详见 | |------|---------|-------------|------| | **标准模式** | 默认 | 20+ section 完整组装，静态/动态分界 | [[14 - System Prompt 架构#二、getSystemPrompt() 完整组装顺序]] | | **Proactive/KAIROS 模式** | `feature('PROACTIVE')` 或 `feature('KAIROS')` | 精简自主代理 prompt + `# Autonomous work` 长指令 | [[14 - System Prompt 架构#八、Proactive/KAIROS 自主代理模式]] | | **Coordinator 模式** | `feature('COORDINATOR_MODE')` + 环境变量 | 专用协调者 prompt，包含 worker 管理协议 | [[10 - 多 Agent 与协调器]] [[15 - Agent 与 SubAgent Prompt]] | | **Simple 模式** | `CLAUDE_CODE_SIMPLE=true` | 极简三行 prompt（角色 + CWD + 日期） | [[14 - System Prompt 架构#简单模式]] | ## 核心设计原则 > [!important] 8 大核心设计原则 > 这些原则贯穿整个 Prompt 体系，是理解 Claude Code 架构的关键。 1. **模块化数组架构** — System prompt 是 `string[]` 而非单字符串，支持分段缓存（[[14 - System Prompt 架构#五、Section 缓存机制]]） 2. **静态/动态分界** — `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 将可全局缓存的内容与动态内容分离（[[16 - Prompt Caching 与 Context 管理]]） 3. **缓存感知设计** — 从路径规范化到 Agent 列表外移，处处考虑缓存命中率（[[19 - Prompt 工程技巧与设计模式]]） 4. **纵深防御安全** — Prompt 层 + 规则层 + 工具层 + 沙箱层 + AI 分类器，即使 bypass 也有不可绕过的检查（[[17 - 权限系统与 Safety Prompt]]） 5. **永不委派理解** — Coordinator 必须理解 worker 结果后再下达指令，禁止懒惰委派（[[15 - Agent 与 SubAgent Prompt]]） 6. **Scratchpad CoT** — `` 让模型先思考再输出，后处理删除中间推理（[[19 - Prompt 工程技巧与设计模式]]） 7. **DANGEROUS_ 命名约定** — 非缓存 section 用 `DANGEROUS_uncachedSystemPromptSection` 命名，刻意制造审查摩擦（[[14 - System Prompt 架构#五、Section 缓存机制]]） 8. **三层注入架构** — System Prompt（数组）+ System Context（key-value 追加到系统末尾）+ User Context（key-value 作为首条用户消息），CLAUDE.md 放在 user message 保持 system prompt 缓存稳定性（[[18 - Memory 与 Hooks 系统]]） --- #claude-code #prompt-engineering #system-prompt #architecture #caching #safety #multi-agent